home *** CD-ROM | disk | FTP | other *** search
/ Delphi Magazine Collection 2001 / Delphi Magazine Collection 20001 (2001).iso / DISKS / Issue35 / eval_dan / EVAL_DAN.ZIP / readme.txt < prev   
Encoding:
Text File  |  1997-12-30  |  10.1 KB  |  223 lines
  1. Expression Evaluator and TAxesView ReadMe
  2. Daniel Bryant  (c)1997
  3. --------------------------------------------------------------------
  4.  
  5. Installing and running the software:
  6.     Simply move the uninstalled files to the directory of your
  7. choice and run the executable (mathtstp.exe)  No files are needed
  8. in the run-path in order for it to function.  If you wish to 
  9. recompile the source you will need a copy of Borland's Delphi 2.0
  10. or later.
  11.  
  12. Installing the TAxesView component:
  13.     Included in with the source for the evaluator is a 
  14. component that allows you to create a set of 2d axes.  It is not 
  15. very useful in and of itself, but it can be used as a base class
  16. from which to descend any object which needs to draw data on a 
  17. grid in 2d space with axes.  To install the component, use the 
  18. normal Delphi 2 or 3 installation method outlined in the Delphi
  19. help files.
  20.  
  21. Using the software
  22. --------------------------------------------------------------------
  23.     The software is provided as a demo by which you can see the
  24. abilities of the expression evaluator.  On the left side of the
  25. window is a button marked "Make Tree", as well as a data entry box 
  26. and a second button marked "Calculate".  The data entry box is used
  27. to enter the expression that you wish to evaluate.  When the
  28. expression is fully and correctly typed in, click on the "Make Tree"
  29. button.  This will generate an expression evaluation tree which will
  30. appear in the panel on the right of the window, as well as a list of
  31. parsing tokens which appear on the box under the "Tokens" tab.  For
  32. more details on the evaluation tree, read further on in the 
  33. documentation.  To evaluate the expression once the tree has been 
  34. built, just click on "Evaluate".  This will evaluate your expression
  35. (assuming it is a valid expression), defaulting any unknown variables
  36. in the expression to 0.
  37.     To change variable values, click on the "Variables" tab at 
  38. the bottom of the window.  A list of any variables that have already
  39. been created will appear.  To create a new variable or change an
  40. existing one, simply type in the name and value in the data entry
  41. boxes provided and then click on "Set".  The display will update
  42. accordingly.  To delete a variable in the list, select it in the list
  43. and click on"Delete".  To clear the list of variables, click on 
  44. "Clear".
  45.  
  46. The evaluation tree
  47. --------------------------------------------------------------------
  48.     The evaluation tree at the right side of the window is a 
  49. graphical display of the tree stored in memory used to evaluate the
  50. expressions.  This is useful for debugging purposes and also helps
  51. to visualize how the evaluator works.  The nice thing about using
  52. evaluation trees is that you only have to create them once for any
  53. given expression--including expressions that contain variables.
  54.     The tree is evaluated from bottom to top by the use of a
  55. recursive routine.  Operations with lower priority (lower in the
  56. order of operations) will tend to be higher on the tree, while
  57. operations of higher priority will tend to be lower.  The exception
  58. to this is parentheses which override the standard order of 
  59. operations and end up creating a smaller tree within the main tree.
  60.     To read the tree, simply look at each symbol on the tree.  
  61. Operations are represented by the standard entry symbol and each
  62. operation becomes a parental node on the tree.  Each operation then
  63. has either more operations, numbers, or variables below it.  Most
  64. operations are performed between the first and second value.  For
  65. example:
  66.     +
  67.     |
  68.     ----A
  69.     |
  70.     ----B
  71.  
  72. This would mean A+B and this is the tree you would create if you
  73. type A+B into the data entry box and click on "Make Tree".  The
  74. order really only becomes important when working with symbols such
  75. as '^'(exponent) or '/'(divide).
  76.  
  77. Contacting the author
  78. --------------------------------------------------------------------
  79. I always welcome any comments and/or constructive criticisms
  80. regarding my work.  If you have made any major changes that might 
  81. prove useful, by all means share :-)
  82.  
  83. Daniel Bryant--Email: 
  84. COMPUSERVE: aabryant@compuserve.com
  85. MSN: allenbryant@msn.com
  86.  
  87. I prefer that you use the compuserve account, but I also check my
  88. MSN mail occassionally.
  89.  
  90. You can also post a message in the Compuserve Games Developers'
  91. Forum (GO GAMEDEV) to 75544,2762.  I'm a frequent visitor so
  92. I'll be sure to get your message.
  93.  
  94. Reference guide to the objects used for expression evaluation
  95. --------------------------------------------------------------------
  96.   TTokenType = (ttUnknown,ttOperation,ttVariable,ttConstant);
  97.  
  98. This is used to store the possible states for any given node in the
  99. tree.  ttUnknown means that the value has not been defined yet.
  100. ttOperation means that this is some sort of operation that works on
  101. the values generated by its children nodes.  ttVariable means that
  102. this is a variable that can change values over time.  ttConstant
  103. means that this is a numeric constant that can be accessed directly.
  104.  
  105.   PVariableRecord = ^TVariableRecord;
  106.   TVariableRecord = record
  107.     VarData: Double;
  108.     VarName: String;
  109.   end;
  110.  
  111. This record is used to store variable information.  PVariableRecord
  112. is used to store pointers to variables in a TVarList.
  113.  
  114.   TVarList = class(TList)
  115.   private
  116.     function GetVars(Index: String): PVariableRecord;
  117.   public
  118.     property Vars[Index: String]: PVariableRecord read GetVars;
  119.     //Methods
  120.     destructor Destroy; override;
  121.     function GetIndex(AValue: String): Integer;
  122.     function NewVar(AName: String; AData: Double): PVariableRecord;
  123.   end;
  124.  
  125. This class based on TList is used as a method by which to store a
  126. list of variables.  It has built-in support for accessing variables
  127. by name, as well as a convenient way to set/create variable data
  128. through NewVar--if the variable already exists it just changes
  129. whatever data there already is.
  130.  
  131.   TExpressionNode = class(TObject)
  132.   private
  133.     FValue: String;
  134.     FParent: TExpressionNode;
  135.     FTokenType: TTokenType;
  136.     FChildren: TList;
  137.     FValidValue: Boolean;
  138.     FNumValue: Double;
  139.     FVarPointer: PVariableRecord;
  140.     FTree: TExpressionTree;
  141.   public
  142.     property Value: String read FValue write FValue;
  143.     property Parent: TExpressionNode read FParent write FParent;
  144.     property TokenType: TTokenType read FTokenType write FTokenType;
  145.     property Children: TList read FChildren write FChildren;
  146.     property ValidValue: Boolean read FValidValue write FValidValue;
  147.     property NumValue: Double read FNumValue write FNumValue;
  148.     property VarPointer: PVariableRecord read FVarPointer write FVarPointer;
  149.     property Tree: TExpressionTree read FTree write FTree;
  150.     //Methods
  151.     function CreateChild: TExpressionNode;
  152.     function Evaluate(SuppressErrors,UseVars: Boolean): Double;
  153.     constructor Create(AOwner: TExpressionNode; ATree: TExpressionTree);
  154.     destructor Destroy; override;
  155.   end;
  156.  
  157. This is an important part of the expression evaluator as it contains
  158. all of the data relevant to each node in the evaluation tree.  It's 
  159. value property simply contains the string token that spawned it--i.e.
  160. '+','100','D',etc.  Parent is a pointer to its parent node.  If Parent
  161. is nil then this node should be the top of the tree.  TokenType
  162. contains information as to exactly what type of token it is--see the
  163. declaration for TTokenType enumerated type above.  Children contains
  164. a list of all the children nodes this node has.  ValidValue is used
  165. by the expression evaluator to determine if NumValue is currently
  166. valid--this can (and will be) used to write a procedure to simplify
  167. a given tree down to eliminate redundant constant operations with no
  168. variables.  NumValue contains the numeric value at this point in the
  169. tree counting everything below it--it's only valid if ValidValue is
  170. true.  VarPointer is used for variable nodes to keep a pointer to
  171. their associated variable.  Tree contains a pointer back to the tree
  172. which contains the nodes.  CreateChild is used to create a new child
  173. node.  Evaluate is to evaluate the tree from this node onward.  The 
  174. constructor and destructor should be obvious.
  175.  
  176.   TExpressionTree = class(TPersistent)
  177.   private
  178.     FTopNode: TExpressionNode;
  179.     FExpression: String;
  180.     FCheckSyntax: Boolean;
  181.     FTokens: TStringList;
  182.     FVarList: TVarList;
  183.     procedure SetExpression(AValue: String);
  184.   public
  185.     property TopNode: TExpressionNode read FTopNode write FTopNode;
  186.     property Expression: String read FExpression write SetExpression;
  187.     property CheckSyntax: Boolean read FCheckSyntax write FCheckSyntax;
  188.     property Tokens: TStringList read FTokens write FTokens;
  189.     property VarList: TVarList read FVarList write FVarList;
  190.     //Methods
  191.     constructor Create;
  192.     destructor Destroy; override;
  193.     procedure MakeTokens;
  194.     procedure RemoveBadTokens;
  195.   end;
  196.  
  197. This class is used to contain the evaluation tree and also generate
  198. the tree.  TopNode contains a pointer to the top node of the tree--
  199. this may or may not be nil at any given time.  Expression contains
  200. the current expression that is in the evaluation tree--set this
  201. value to create a new tree.  CheckSyntax, if set, will cause the 
  202. object to check for syntax errors in the expression before the tree
  203. is created (this only checks for parentheses balance right now.)
  204. Tokens is a list of all of the tokens generated by the parser 
  205. [MakeTokens].  VarList is a pointer to a variable list that can be
  206. used while evaluating the expression (not created automatically.)
  207. Call MakeTokens to create a rudimentary parse list from Expression
  208. and then call RemoveBadTokens to remove any redundant tokens that
  209. will cause undesired behavior (currently only checks for a single
  210. token enclosed in parentheses--i.e. '(A)')
  211.  
  212. For reasons of length, I have decided not to include a reference to
  213. TAxesView or any of the other objects related to it, but with a 
  214. little experimentation and a peek at the source it should not be too
  215. difficult to use and/or modify.
  216.  
  217.  
  218.  
  219. LEGAL NOTICE:
  220. BOTH THIS SOFTWARE AND ALL ASSOCIATED MATERIALS INCLUDING SOURCE AND
  221. DOCUMENTATION ARE COPYRIGHTED FREEWARE.  THEY MAY BE USED FREELY FOR
  222. ALL PURPOSES, COMMERCIAL AND NON-COMMERCIAL, AS LONG AS THE ORIGINAL
  223. AUTHOR OF THE SOFTWARE IS CREDITED FOR HIS WORK.